5 Basic Types

This is the general syntax of a type specification:

name ::= (name [keyword argument]... args)
     |   name

Where, name is a widget name, keyword is the name of a property, argument is the value of the property, and args are interpreted in a widget specific way.

The following keyword arguments apply to all widgets:

:value

The initial value for widgets of this type.

:format

This string will be inserted in the buffer when you create a widget. The following ‘%’ escapes are available:

‘%[’

‘%]’

The text inside will be marked as a button.

By default, the text will be shown in widget-button-face, and surrounded by brackets.

User Option: widget-button-prefix

String to prefix buttons.

User Option: widget-button-suffix

String to suffix buttons.

‘%{’

‘%}’

The text inside will be displayed with the face specified by :sample-face.

‘%v’

This will be replaced with the buffer representation of the widget’s value. What this is depends on the widget type.

Warning: In an editable-field widget, the ‘%v’ escape must be preceded by some other text in the format string (if specified).

‘%d’

Insert the string specified by :doc here.

‘%h’

Like ‘%d’, with the following modifications: If the documentation string is more than one line, it will add a button which will toggle between showing only the first line, and showing the full text. Furthermore, if there is no :doc property in the widget, it will instead examine the :documentation-property property. If it is a lambda expression, it will be called with the widget’s value as an argument, and the result will be used as the documentation text.

‘%t’

Insert the string specified by :tag here, or the princ representation of the value if there is no tag.

‘%%’

Insert a literal ‘%’.

:button-face

Face used to highlight text inside %[ %] in the format.

:button-prefix

:button-suffix

Text around %[ %] in the format.

These can be

nil

No text is inserted.

a string

The string is inserted literally.

a symbol

The value of the symbol is expanded according to this table.

:doc

The string inserted by the ‘%d’ escape in the format string.

:tag

The string inserted by the ‘%t’ escape in the format string.

:tag-glyph

Name of image to use instead of the string specified by :tag on Emacsen that supports it.

:help-echo

Specifies how to display a message whenever you move to the widget with either widget-forward or widget-backward or move the mouse over it (using the standard help-echo mechanism). The argument is either a string to display, a function of one argument, the widget, which should return a string to display, or a form that evaluates to such a string.

:follow-link

Specifies how to interpret a mouse-1 click on the widget. See Defining Clickable Text in the Emacs Lisp Reference Manual.

:indent

An integer indicating the absolute number of spaces to indent children of this widget.

:offset

An integer indicating how many extra spaces to add to the widget’s grandchildren compared to this widget.

:extra-offset

An integer indicating how many extra spaces to add to the widget’s children compared to this widget.

:notify

A function called each time the widget or a nested widget is changed. The function is called with two or three arguments. The first argument is the widget itself, the second argument is the widget that was changed, and the third argument is the event leading to the change, if any.

:menu-tag

Tag used in the menu when the widget is used as an option in a menu-choice widget.

:menu-tag-get

Function used for finding the tag when the widget is used as an option in a menu-choice widget. By default, the tag used will be either the :menu-tag or :tag property if present, or the princ representation of the :value property if not.

:match

Should be a function called with two arguments, the widget and a value, and returning non-nil if the widget can represent the specified value.

:validate

A function which takes a widget as an argument, and returns nil if the widget’s current value is valid for the widget. Otherwise it should return the widget containing the invalid data, and set that widget’s :error property to a string explaining the error.

The following predefined function can be used:

Function: widget-children-validate widget

All the :children of widget must be valid.

:tab-order

Specify the order in which widgets are traversed with widget-forward or widget-backward. This is only partially implemented.

1. Widgets with tabbing order -1 are ignored.
2. (Unimplemented) When on a widget with tabbing order n, go to the next widget in the buffer with tabbing order n+1 or nil, whichever comes first.
3. When on a widget with no tabbing order specified, go to the next widget in the buffer with a positive tabbing order, or nil

:parent

The parent of a nested widget (e.g., a menu-choice item or an element of a editable-list widget).

:sibling-args

This keyword is only used for members of a radio-button-choice or checklist. The value should be a list of extra keyword arguments, which will be used when creating the radio-button or checkbox associated with this item.

User Option: widget-glyph-directory

Directory where glyphs are found. Widget will look here for a file with the same name as specified for the image, with either a .xpm (if supported) or .xbm extension.

User Option: widget-glyph-enable

If non-nil, allow glyphs to appear on displays where they are supported.